<p>Try to imagine using the standard Java API (Collections, JDBC, IO, …​) without Javadoc. It would be a nightmare, because Javadoc is the only way to
understand of the contract of the API. Documenting an API with Javadoc increases the productivity of the developers consuming it.</p>
<p>On top of a main description for each member of a public API, the following Javadoc elements are required to be described:</p>
<ul>
  <li> Parameters, using <code>@param parameterName</code>. </li>
  <li> Thrown exceptions, using <code>@throws exceptionName</code>. </li>
  <li> Method return values, using <code>@return</code>. </li>
  <li> Generic types, using <code>@param &lt;T&gt;</code>. </li>
</ul>
<p>Furthermore the following guidelines should be followed:</p>
<ul>
  <li> At least 1 line of description. </li>
  <li> All parameters documented with <code>@param</code>, and names should match. </li>
  <li> All checked exceptions documented with <code>@throws</code> </li>
  <li> <code>@return</code> present and documented when not <code>void</code>. </li>
  <li> Placeholders like <code>"TODO"</code>, <code>"FIXME"</code>, <code>"..."</code> should be avoided. </li>
</ul>
<p>The following public methods and constructors are not taken into account by this rule:</p>
<ul>
  <li> Getters and setters. </li>
  <li> Methods overriding another method (usually decorated with <code>@Override</code>). </li>
  <li> Empty constructors. </li>
  <li> Static constants. </li>
</ul>
<p>For the parameters of the rule, the following rules are applied:</p>
<ul>
  <li> <code>?</code> matches a single character </li>
  <li> <code>*</code> matches zero or more characters </li>
  <li> <code>**</code> matches zero or more packages </li>
</ul>
<p>Examples:</p>
<ul>
  <li> <code>java.internal.InternalClass</code> will match only <code>InternalClass</code> class. </li>
  <li> <code>java.internal.*</code> will match any member of <code>java.internal</code> package. </li>
  <li> <code>java.internal.**</code> same as above, but including sub-packages. </li>
</ul>
<h2>Noncompliant Code Example</h2>
<pre>
/**
  * This is a Javadoc comment
  */
public class MyClass&lt;T&gt; implements Runnable {    // Noncompliant - missing '@param &lt;T&gt;'

  public static final DEFAULT_STATUS = 0;    // Compliant - static constant
  private int status;                           // Compliant - not public

  public String message;                  // Noncompliant

  public MyClass() {                         // Noncompliant - missing documentation
    this.status = DEFAULT_STATUS;
  }

  public void setStatus(int status) {  // Compliant - setter
    this.status = status;
  }

  @Override
  public void run() {                          // Compliant - has @Override annotation
  }

  protected void doSomething() {    // Compliant - not public
  }

  public void doSomething2(int value) {  // Noncompliant
  }

  public int doSomething3(int value) {  // Noncompliant
    return value;
  }
}
</pre>
<h2>Compliant Solution</h2>
<pre>
/**
  * This is a Javadoc comment
  * @param &lt;T&gt; the parameter of the class
  */
public class MyClass&lt;T&gt; implements Runnable {

  public static final DEFAULT_STATUS = 0;
  private int status;

  /**
    * This is a Javadoc comment
    */
  public String message;

  /**
   * Class comment...
   */
  public MyClass() {
    this.status = DEFAULT_STATUS;
  }

  public void setStatus(int status) {
    this.status = status;
  }

  @Override
  public void run() {
  }

  protected void doSomething() {
  }

  /**
    * Will do something.
    * @param value the value to be used
    */
  public void doSomething(int value) {

  /**
    *  {@inheritDoc}
    */
  public int doSomething(int value) {
    return value;
  }
}
</pre>

